Name the Python extension after what it contains - #21816
Conversation
|
Stack from ghstack (oldest at bottom): |
🔗 Helpful Links🧪 See artifacts and rendered test results at hud.pytorch.org/pr/pytorch/executorch/21816
Note: Links to docs will display an error until the docs builds have been completed. ⏳ No Failures, 33 PendingAs of commit dfb5eb1 with merge base 4724088 ( This comment was automatically generated by Dr. CI and updates every 15 minutes. |
The compiled Python extension in the wheel was called `_portable_lib`. That name is misleading in two ways. "Portable" is the name of a kernel set in this project, the portable kernels, and this file does not contain them: it holds the Python bindings for the runtime. "Lib" says nothing, since every shared object is a library. Someone looking for the portable kernels finds the Python bindings instead, and someone looking for the bindings has no reason to open a file named after kernels. Rename it to `_C`, which is the usual name for a package's compiled C extension and what PyTorch calls the same thing (`torch/_C.cpython-*.so`). The package path already says `pybindings`, as in `executorch.extension.pybindings`, so a name like `_pybindings` would repeat itself while `_C` reads as "this package's C extension". Nothing user facing changes. Applications import the public wrapper: ```python from executorch.extension.pybindings import portable_lib ``` That wrapper re-exports everything from the compiled module and keeps its name, so existing code continues to work. Only the private module behind it is renamed, and it was already documented as experimental and subject to change. Test plan: Built a wheel and confirmed the shipped file is named for the new module: ``` extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so ``` Installed that wheel into a fresh environment and checked both the public wrapper and the private module load, then exported and ran a model through the Python bindings: ``` public wrapper works: True module name : executorch.extension.pybindings._C exported symbols : 22 ``` Also grepped the tree to confirm no build file, test, or comment still names the old module. ghstack-source-id: 20f23fe ghstack-comment-id: 5282557165 Pull-Request: #21816
The compiled Python extension in the wheel was called `_portable_lib`. That name is misleading in two ways. "Portable" is the name of a kernel set in this project, the portable kernels, and this file does not contain them: it holds the Python bindings for the runtime. "Lib" says nothing, since every shared object is a library. Someone looking for the portable kernels finds the Python bindings instead, and someone looking for the bindings has no reason to open a file named after kernels. Rename it to `_C`, which is the usual name for a package's compiled C extension and what PyTorch calls the same thing (`torch/_C.cpython-*.so`). The package path already says `pybindings`, as in `executorch.extension.pybindings`, so a name like `_pybindings` would repeat itself while `_C` reads as "this package's C extension". Nothing user facing changes. Applications import the public wrapper: ```python from executorch.extension.pybindings import portable_lib ``` That wrapper re-exports everything from the compiled module and keeps its name, so existing code continues to work. Only the private module behind it is renamed, and it was already documented as experimental and subject to change. Test plan: Built a wheel and confirmed the shipped file is named for the new module: ``` extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so ``` Installed that wheel into a fresh environment and checked both the public wrapper and the private module load, then exported and ran a model through the Python bindings: ``` public wrapper works: True module name : executorch.extension.pybindings._C exported symbols : 22 ``` Also grepped the tree to confirm no build file, test, or comment still names the old module. ghstack-source-id: 5386d2f ghstack-comment-id: 5282557165 Pull-Request: #21816
The compiled Python extension in the wheel was called `_portable_lib`. That name is misleading in two ways. "Portable" is the name of a kernel set in this project, the portable kernels, and this file does not contain them: it holds the Python bindings for the runtime. "Lib" says nothing, since every shared object is a library. Someone looking for the portable kernels finds the Python bindings instead, and someone looking for the bindings has no reason to open a file named after kernels. Rename it to `_C`, which is the usual name for a package's compiled C extension and what PyTorch calls the same thing (`torch/_C.cpython-*.so`). The package path already says `pybindings`, as in `executorch.extension.pybindings`, so a name like `_pybindings` would repeat itself while `_C` reads as "this package's C extension". Nothing user facing changes. Applications import the public wrapper: ```python from executorch.extension.pybindings import portable_lib ``` That wrapper re-exports everything from the compiled module and keeps its name, so existing code continues to work. Only the private module behind it is renamed, and it was already documented as experimental and subject to change. Test plan: Built a wheel and confirmed the shipped file is named for the new module: ``` extension/pybindings/_C.cpython-312-x86_64-linux-gnu.so ``` Installed that wheel into a fresh environment and checked both the public wrapper and the private module load, then exported and ran a model through the Python bindings: ``` public wrapper works: True module name : executorch.extension.pybindings._C exported symbols : 22 ``` Also grepped the tree to confirm no build file, test, or comment still names the old module. ghstack-source-id: e6925ec ghstack-comment-id: 5282557165 Pull-Request: #21816
This PR needs a
|
The compiled Python extension in the wheel was called
_portable_lib. That nameis misleading in two ways. "Portable" is the name of a kernel set in this project,
the portable kernels, and this file does not contain them: it holds the Python
bindings for the runtime. "Lib" says nothing, since every shared object is a
library. Someone looking for the portable kernels finds the Python bindings
instead, and someone looking for the bindings has no reason to open a file named
after kernels.
Rename it to
_C, which is the usual name for a package's compiled C extensionand what PyTorch calls the same thing (
torch/_C.cpython-*.so). The package pathalready says
pybindings, as inexecutorch.extension.pybindings, so a name like_pybindingswould repeat itself while_Creads as "this package's Cextension".
The documented import path is unaffected. Applications import the public wrapper:
That wrapper re-exports everything from the compiled module and keeps its name, so
code using it continues to work.
Code that imports the private module directly does break, and that pattern is in
real use despite the module being documented as experimental and subject to change.
No Python alias is added for the old name, since keeping the name reachable would
leave in place the thing this change exists to remove; such a caller moves to the
public wrapper.
The CMake target of that name is also gone, and this is a compatibility break worth
stating plainly. Version 1.4.1 published it, as
add_library(_portable_lib STATIC IMPORTED), and put it inEXECUTORCH_LIBRARIES. A project that names it directly nolonger configures and should link
executorch::runtimeinstead.Keeping the name was tried and dropped. Aliasing it to the runtime looked compatible
and was not: the published target was mutable and demanded C++20, and
$<TARGET_FILE:>on it named the extension, so an alias silently moved the consumerto C++17, changed the file that expression resolves to, and made
set_propertyon ita hard error because an alias is immutable. Pointing it back at the extension is not an
option either: that file holds unresolved interpreter symbols, so a plain C++
application that links it fails to link or dies at startup.
What a consumer using the documented
EXECUTORCH_LIBRARIESvariable gets also changes,for the better. In 1.4.1 that variable held the Python extension, so linking it from
C++ could not work. It now holds the runtime and the kernel and backend libraries,
which is what such a project wanted.
Test plan:
Built a wheel and confirmed the shipped file is named for the new module:
Installed that wheel into a fresh environment and checked both the public wrapper
and the private module load, then exported and ran a model through the Python
bindings:
Also grepped the tree. The only place the old extension name survives is the
package config, where the compatibility aliases keep it on purpose. The other
matches name the portable kernels library, which is a different thing.